<!doctype html public "-//W3C//DTD HTML 4.0 Frameset//EN""http://www.w3.org/TR/REC-html40/frameset.dtd">
<html>
<head>
<title>
JsWs Overview
</title>
<link rel ="stylesheet" type="text/css" href="stylesheet.css" title="Style">
<script>
function asd() {
	
		parent.document.title="db.js Overview";
	
}
</script>
</head>
<body bgcolor="white" onload="asd();">

<!-- ========== START OF NAVBAR ========== -->
<a name="navbar_top"><!-- --></a>
<table border="0" width="100%" cellpadding="1" cellspacing="0">
<tr>
<td colspan=2 bgcolor="#EEEEFF" class="NavBarCell1">
<a name="navbar_top_firstrow"><!-- --></a>
<table border="0" cellpadding="0" cellspacing="3">
  <tr align="center" valign="top">
  
  
  <td bgcolor="#EEEEFF" class="NavBarCell1">    <a href="overview-summary.html"><font class="NavBarFont1"><b>Overview</b></font></a>&nbsp;</td>
  <td bgcolor="#FFFFFF" class="NavBarCell1Rev">	&nbsp;<font class="NavBarFont1Rev"><b>File</b></font>&nbsp;</td>
  

  <td bgcolor="#FFFFFF" class="NavBarCell1"> 	<font class="NavBarFont1">Class</font>&nbsp;</td>
  <td bgcolor="#EEEEFF" class="NavBarCell1">    <a href="overview-tree.html"><font class="NavBarFont1"><b>Tree</b></font></a>&nbsp;</td>
  <td bgcolor="#EEEEFF" class="NavBarCell1">    <a href="index-all.html"--><font class="NavBarFont1"><b>Index</b></font></a>&nbsp;</td>
  <td bgcolor="#EEEEFF" class="NavBarCell1">    <a href="help-doc.html"><font class="NavBarFont1"><b>Help</b></font></a>&nbsp;</td>
  </tr>
</table>
</td>
<td bgcolor="#EEEEFF" align="right" valign="top">
<em>
<b>JsWs</b></em>
</td>
</tr>

<tr>
<td bgcolor="white" class="NavBarCell2"><font size="-2">
&nbsp;PREV&nbsp;
&nbsp;NEXT</font></td>
<td bgcolor="white" class="NavBarCell2"><font size="-2">
  <a href="index.html" target="_top"><b>FRAMES</b></a>  &nbsp;
&nbsp;<a href="overview-summary.html" target="_top"><b>NO FRAMES</b></a>
&nbsp;&nbsp;
<script>
  <!--
  if(window==top) {
    document.writeln('<A HREF="allclasses-noframe.html" TARGET=""><B>All Classes</B></A>');
  }
  //-->
</script>
<noscript>
<a href="allclasses-noframe.html" target=""><b>All Classes</b></a>
</noscript>
</font></td>
</tr>
</table>
<!-- =========== END OF NAVBAR =========== -->

<hr>
<center>
	
	   <h2>db.js</h2>
	
</center>

	


<h4>Summary</h4>
<p>
	
		No overview generated for 'db.js'<BR/><BR/>
	
</p>

<hr>


    <table border="1" cellpadding="3" cellspacing="0" width="100%">
    <tr bgcolor="#CCCCFF" class="TableHeadingColor">
    <td colspan=2><font size="+2">
    
        <b>Class Summary</b>
    
    </font></td>
    </tr>
    
    <tr bgcolor="white" class="TableRowColor">
    <td width="15%"><b><a href="DbColumn.html">DbColumn</a></b></td>
    <td>Represents a column in a DB table
 </td>
    </tr>
    
    <tr bgcolor="white" class="TableRowColor">
    <td width="15%"><b><a href="DbConnection.html">DbConnection</a></b></td>
    <td>Responsible for creating and opening SQLite/MozStorage files.</td>
    </tr>
    
    <tr bgcolor="white" class="TableRowColor">
    <td width="15%"><b><a href="DbQuery.html">DbQuery</a></b></td>
    <td>Represents a prepared statement ready for execution with or
  without parameters.</td>
    </tr>
    
    <tr bgcolor="white" class="TableRowColor">
    <td width="15%"><b><a href="DbTable.html">DbTable</a></b></td>
    <td>Looks up and represents metadata for a DB table
 </td>
    </tr>
    
    <tr bgcolor="white" class="TableRowColor">
    <td width="15%"><b><a href="ExDbError.html">ExDbError</a></b></td>
    <td>Exception class for DB errors
 </td>
    </tr>
    
    </table>
    <hr/> 


<!-- ========== METHOD SUMMARY =========== -->

<!-- ========== END METHOD SUMMARY =========== -->


        <pre class="sourceview"><span class="comment">/* ***** BEGIN LICENSE BLOCK *****
 *   Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is JsWs.
 *
 * The Initial Developer of the Original Code is
 * Chris Winberry.
 * Portions created by the Initial Developer are Copyright (C) 2007
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 * 
 * ***** END LICENSE BLOCK ***** */</span>

<span class="comment">/**
 * <span class="attrib">@class</span> Exception class for DB errors
 * <span class="attrib">@constructor</span>
 * <span class="attrib">@base</span> ExBase
 * <span class="attrib">@param</span> {String} msg Description of exception
 * <span class="attrib">@param</span> {Number} code (optional) Error code
 * <span class="attrib">@param</span> {Exception} ex (optional) An earlier exception to wrap
 * <span class="attrib">@param</span> {Arguments} args (optional) Arguments array of a functions
 * <span class="attrib">@see</span> DbConnection
 * <span class="attrib">@see</span> DbQuery
 */</span>
<span class="reserved">function</span> ExDbError (msg, code, ex, args) { ExDbError.baseConstructor.call(<span class="reserved">this</span>, msg, code, ex, args); }
SubClass(ExBase, ExDbError);


<span class="comment">/**
 * <span class="attrib">@class</span> Represents a column in a DB table
 * <span class="attrib">@constructor</span>
 * <span class="attrib">@param</span> {Hash/Record} row Hash of a row from a record set
 * <span class="attrib">@see</span> DbTable
 */</span>
<span class="reserved">function</span> DbColumn (row) {
	<span class="comment">/**
	 * Name of the column
	 * <span class="attrib">@type</span> String
	 */</span>
	<span class="reserved">this</span>.name = row[<span class="literal">"name"</span>];
	<span class="comment">/**
	 * Columns data type
	 * <span class="attrib">@type</span> String
	 */</span>
	<span class="reserved">this</span>.type = row[<span class="literal">"type"</span>].toLowerCase();
	<span class="comment">/**
	 * ID of the column
	 * <span class="attrib">@type</span> String
	 */</span>
	<span class="reserved">this</span>.id = row[<span class="literal">"cid"</span>];
	<span class="comment">/**
	 * Column's default value
	 * <span class="attrib">@type</span> String
	 */</span>
	<span class="reserved">this</span>.defVal = row[<span class="literal">"dflt_value"</span>];
	<span class="comment">/**
	 * Flag indicating whether the column is a primary key
	 * <span class="attrib">@type</span> Boolean
	 */</span>
	<span class="reserved">this</span>.pk = (row[<span class="literal">"pk"</span>] == 1);
	<span class="comment">/**
	 * Flag indicating if the column allows null values
	 * <span class="attrib">@type</span> Boolean
	 */</span>
	<span class="reserved">this</span>.allowNull = (row[<span class="literal">"notnull"</span>] == 1);
}


<span class="comment">/**
 * <span class="attrib">@class</span> Looks up and represents metadata for a DB table
 * <span class="attrib">@constructor</span>
 * <span class="attrib">@param</span> {String} name Name of the table
 * <span class="attrib">@param</span> {DbConnection} db Database connection to schema that contains the table
 * <span class="attrib">@requires</span> DbColumn
 */</span>
<span class="reserved">function</span> DbTable (name, db) {
	<span class="comment">/**
	 * Name of the table
	 * <span class="attrib">@type</span> String
	 */</span>
	<span class="reserved">this</span>.name = name;
	<span class="comment">/**
	 * Columns of the table
	 * <span class="attrib">@type</span> DbColumn[]
	 */</span>
	<span class="reserved">this</span>.cols = new Array();

	var query = db.prepare(<span class="literal">"PRAGMA TABLE_INFO('"</span> + <span class="reserved">this</span>.name + <span class="literal">"')"</span>);
	var results = query.exec();
	<span class="reserved">for</span> (var i = 0; i &lt; results.length; i++)
		<span class="reserved">this</span>.cols[<span class="reserved">this</span>.cols.length] = new DbColumn(results[i]);

	query.destroy();
}


<span class="comment">/**
 * <span class="attrib">@class</span> Represents a prepared statement ready for execution with or
 *  without parameters. Execution of the query is handled by {<span class="attrib">@link</span> #exec}.
 * <span class="attrib">@constructor</span>
 * <span class="attrib">@param</span> {DbConnection} dbConn Database connection to schema that contains the table
 * <span class="attrib">@param</span> {String} sql SQL statement that was prepared
 * <span class="attrib">@see</span> DbConnection#prepare
 */</span>
<span class="reserved">function</span> DbQuery (dbConn, sql) {
	<span class="comment">/** <span class="attrib">@private</span> */</span>
	<span class="reserved">this</span>._conn = dbConn;
	<span class="comment">/** <span class="attrib">@private</span> */</span>
	<span class="reserved">this</span>._sql = sql;
	<span class="comment">/** <span class="attrib">@private</span> */</span>
	<span class="reserved">this</span>._query = <span class="reserved">this</span>._conn.createStatement(<span class="reserved">this</span>._sql);
}


<span class="comment">/**
 * Executes the prepared statement with any parameters passed in
 * <span class="attrib">@param</span> {Mixed} n Variable number of parameters to be used with the statement
 * <span class="attrib">@return</span> Data returned by the query
 * <span class="attrib">@type</span> {Hash/Record}[]
 */</span>
DbQuery.<span class="reserved">prototype</span>.exec = <span class="reserved">function</span> (<span class="comment">/* n arguments */</span>) {
	<span class="reserved">for</span> (var i = 0; i &lt; arguments.length; i++) {
		<span class="reserved">if</span> (arguments[i] == null)
			<span class="reserved">this</span>._query.bindNullParameter(i);
		<span class="reserved">else</span> <span class="reserved">if</span> (typeof(arguments[i]) == <span class="literal">"string"</span>)
			<span class="reserved">this</span>._query.bindUTF8StringParameter(i, arguments[i]);
		<span class="reserved">else</span> <span class="reserved">if</span> (typeof(arguments[i]) == <span class="literal">"number"</span>)
			<span class="reserved">if</span> (parseInt(arguments[i]) != parseFloat(arguments[i]))
				<span class="reserved">this</span>._query.bindDoubleParameter(i, arguments[i]);
			<span class="reserved">else</span>
				<span class="reserved">this</span>._query.bindInt32Parameter(i, arguments[i]);
		<span class="reserved">else</span>
			<span class="reserved">this</span>._query.bindUTF8StringParameter(i, arguments[i].toString()); <span class="comment">// bindBlobParameter ??? </span>
	}
	
	var result = new Array();
	<span class="reserved">while</span> (<span class="reserved">this</span>._query.executeStep()) {
		var row = new Array();
		<span class="reserved">for</span>(var i = 0; i &lt; <span class="reserved">this</span>._query.columnCount; i++)
			row[<span class="reserved">this</span>._query.getColumnName(i)] = <span class="reserved">this</span>._query.getUTF8String(i);
		result.push(row);
	}

	<span class="reserved">this</span>._query.reset();

	<span class="reserved">return</span>(result);
}


<span class="comment">/**
 * Runs cleanup on internal objects
 */</span>
DbQuery.<span class="reserved">prototype</span>.destroy = <span class="reserved">function</span> () {
	<span class="reserved">this</span>._conn = null;
	<span class="reserved">this</span>._sql = null;
	<span class="reserved">this</span>._query.reset();
	<span class="reserved">this</span>._query = null;
}


<span class="comment">/**
 * <span class="attrib">@class</span> Responsible for creating and opening SQLite/MozStorage files. DB files
 *  that don't exist are automatically created. This also provides
 *  methods to enumerate DB files, schema tables, and table columns.
 * <span class="attrib">@constructor</span>
 * <span class="attrib">@param</span> {String} name Name of the DB schema to open/create
 */</span>
<span class="reserved">function</span> DbConnection (name) {
	<span class="comment">/** <span class="attrib">@private</span> */</span>
	<span class="reserved">this</span>.name = name;
	<span class="comment">/** <span class="attrib">@private</span> */</span>
	<span class="reserved">this</span>.connection = null;
	<span class="reserved">this</span>.open();
}


<span class="comment">/**
 * Opens the DB. If the DB does not exist, it is first created
 * <span class="attrib">@exception</span> ExDbError
 */</span>
DbConnection.<span class="reserved">prototype</span>.open = <span class="reserved">function</span> () {
	var storageService;
	try {
		var file = <span class="reserved">this</span>.dbFolder(); <span class="comment">// ???</span>
		file.append(<span class="reserved">this</span>.name + <span class="literal">"."</span> + <span class="reserved">this</span>._extension); <span class="comment">// ???</span>

		storageService = Cc[<span class="literal">"@mozilla.org/storage/service;1"</span>]
			.getService(Ci.mozIStorageService);

		<span class="reserved">this</span>.connection = storageService.openDatabase(file);
	} catch (ex) {
		<span class="reserved">this</span>.connection = null;
		throw(new ExDbError(<span class="literal">"Failed to create/open the database"</span>, 0, ex, arguments));
	}
}


<span class="comment">/**
 * Closes the DB connection
 */</span>
DbConnection.<span class="reserved">prototype</span>.close = <span class="reserved">function</span> () {
	<span class="reserved">if</span> (<span class="reserved">this</span>.connection == null)
		<span class="reserved">return</span>;
	<span class="reserved">this</span>.destroy();
}


<span class="comment">/**
 * Builds a list of tables that exist in the schema
 * <span class="attrib">@return</span> List of tables in the schema
 * <span class="attrib">@type</span> {<span class="attrib">@link</span> DbTable}[]
 */</span>
DbConnection.<span class="reserved">prototype</span>.tables = <span class="reserved">function</span> () {
	var tables = new Array();
	var query = <span class="reserved">this</span>.prepare(<span class="literal">"SELECT * FROM sqlite_master WHERE type = 'table'"</span>);
	var results = query.exec();
	<span class="reserved">for</span> (var i = 0; i &lt; results.length; i++) {
		var row = results[i];
		tables[tables.length] = new DbTable(row[<span class="literal">"tbl_name"</span>], <span class="reserved">this</span>);
	}
	query.destroy();
	<span class="reserved">return</span>(tables);
}


<span class="comment">/**
 * Immediately execute a query that returns no data
 * and has no parameters
 * <span class="attrib">@param</span> {String} sql SQL query to execute
 * <span class="attrib">@returns</span> Success or failure of the statement execution
 * <span class="attrib">@type</span> Boolean
 * <span class="attrib">@exception</span> ExDbError
 */</span>
DbConnection.<span class="reserved">prototype</span>.execNoResult = <span class="reserved">function</span> (sql) {
	<span class="reserved">if</span> (sql == null || sql == <span class="literal">''</span>)
		throw(new ExDbError(<span class="literal">"SQL statement is null or empty"</span>, 0, null, arguments));
	try {
		<span class="reserved">this</span>.connection.executeSimpleSQL(sql);
	} catch (ex) {
		<span class="reserved">return</span>(false);
	}
	<span class="reserved">return</span>(true);
}


<span class="comment">/**
 * Prepares a SQL statement that returns data and/or has parameters
 * <span class="attrib">@param</span> {String} sql SQL query to execute
 * <span class="attrib">@return</span> Prepare DB query ready for execution
 * <span class="attrib">@type</span> DbQuery
 * <span class="attrib">@exception</span> ExDbError
 */</span>
DbConnection.<span class="reserved">prototype</span>.prepare = <span class="reserved">function</span> (sql) {
	<span class="reserved">if</span> (sql == null || sql == <span class="literal">''</span>)
		throw(new ExDbError(<span class="literal">"SQL statement is null or empty"</span>, 0, null, arguments));
	<span class="reserved">return</span>(new DbQuery(<span class="reserved">this</span>.connection, sql));
}


<span class="comment">/**
 * Runs cleanup on internal objects
 */</span>
DbConnection.<span class="reserved">prototype</span>.destroy = <span class="reserved">function</span> () {
	<span class="reserved">this</span>.connection = null;
}


<span class="comment">/** <span class="attrib">@private</span> */</span>
DbConnection._extension = JSWS_DB_FILEEXT;
<span class="comment">/** <span class="attrib">@ignore</span> */</span>
DbConnection.<span class="reserved">prototype</span>._extension = DbConnection._extension;

<span class="comment">/**
 * Directory where DB files are stored
 * <span class="attrib">@return</span> Directory where DB files are stored
 * <span class="attrib">@type</span> nsIFile
 */</span>
DbConnection.dbFolder = <span class="reserved">function</span> () {
	var file = Cc[<span class="literal">"@mozilla.org/file/directory_service;1"</span>]
		.getService(Ci.nsIProperties)
		.get(<span class="literal">"ProfD"</span>, Ci.nsIFile);
	JsWs.tools.appendPath(file, JSWS_ROOT);
	JsWs.tools.appendPath(file, JSWS_DB_ROOT);
	<span class="reserved">return</span>(file);
}


<span class="comment">/** <span class="attrib">@ignore</span> */</span>
DbConnection.<span class="reserved">prototype</span>.dbFolder = DbConnection.dbFolder;

<span class="comment">/**
 * Builds a list of existing DB schemas (files)
 * <span class="attrib">@return</span> An array of existing DB schemas
 * <span class="attrib">@type</span> String[]
 */</span>
DbConnection.schemas = <span class="reserved">function</span> () {
	var file = DbConnection.dbFolder();
	var dirEntries = file.directoryEntries;
	var reStorage = new RegExp(<span class="literal">"(.+)\\."</span> + DbConnection._extension + <span class="literal">"$"</span>, <span class="literal">"i"</span>);
	var dbs = new Array();
	<span class="reserved">while</span> (dirEntries.hasMoreElements()) {
		var dirEntry = dirEntries.getNext().QueryInterface(Ci.nsIFile);
		<span class="reserved">if</span> (!dirEntry.isDirectory()) {
			var found = reStorage.exec(dirEntry.leafName);
			<span class="reserved">if</span> (found)
				dbs.push(found[1]);
		}
	}
	<span class="reserved">return</span>(dbs);
}


<span class="comment">/** <span class="attrib">@ignore</span> */</span>
DbConnection.<span class="reserved">prototype</span>.schemas = DbConnection.schemas;
</pre>
	<hr>



<!-- ========== START OF NAVBAR ========== -->
<a name="navbar_top"><!-- --></a>
<table border="0" width="100%" cellpadding="1" cellspacing="0">
<tr>
<td colspan=2 bgcolor="#EEEEFF" class="NavBarCell1">
<a name="navbar_top_firstrow"><!-- --></a>
<table border="0" cellpadding="0" cellspacing="3">
  <tr align="center" valign="top">
  
  
  <td bgcolor="#EEEEFF" class="NavBarCell1">    <a href="overview-summary.html"><font class="NavBarFont1"><b>Overview</b></font></a>&nbsp;</td>
  <td bgcolor="#FFFFFF" class="NavBarCell1Rev">	&nbsp;<font class="NavBarFont1Rev"><b>File</b></font>&nbsp;</td>
  

  <td bgcolor="#FFFFFF" class="NavBarCell1"> <font class="NavBarFont1">Class</font>&nbsp;</td>
  <td bgcolor="#EEEEFF" class="NavBarCell1">    <a href="overview-tree.html"><font class="NavBarFont1"><b>Tree</b></font></a>&nbsp;</td>
  <td bgcolor="#EEEEFF" class="NavBarCell1">    <a href="index-all.html"--><font class="NavBarFont1"><b>Index</b></font></a>&nbsp;</td>
  <td bgcolor="#EEEEFF" class="NavBarCell1">    <a href="help-doc.html"><font class="NavBarFont1"><b>Help</b></font></a>&nbsp;</td>
  </tr>
</table>
</td>
<td bgcolor="#EEEEFF" align="right" valign="top"><em>
<b>JsWs</b></em>
</td>
</tr>

<tr>
<td bgcolor="white" class="NavBarCell2"><font size="-2">
&nbsp;PREV&nbsp;
&nbsp;NEXT</font></td>
<td bgcolor="white" class="NavBarCell2"><font size="-2">
  <a href="index.html" target="_top"><b>FRAMES</b></a>  &nbsp;
&nbsp;<a href="overview-summary.html" target="_top"><b>NO FRAMES</b></a>
&nbsp;&nbsp;
<script>
  <!--
  if(window==top) {
    document.writeln('<A HREF="allclasses-noframe.html" TARGET=""><B>All Classes</B></A>');
  }
  //-->
</script>
<noscript>
<a href="allclasses-noframe.html" target=""><b>All Classes</b></a>
</noscript>
</font></td>
</tr>
</table>
<!-- =========== END OF NAVBAR =========== -->

<hr>
<font size="-1">

</font>
<div class="jsdoc_ctime">Documentation generated by <a href="http://jsdoc.sourceforge.net/" target="_parent">JSDoc</a> on Thu Nov  8 22:50:16 2007</div>
</body>
</html>
